/*******************************************************************************
 * Copyright (c) 2004, 2008 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 * 
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.aseclipse.core.runtime.registry.classes {

import org.aseclipse.core.runtime.registry.IExtension;
import org.aseclipse.core.runtime.registry.IExtensionChangeHandler;

/**
 * An extension tracker keeps associations between extensions and their derived objects on an extension basis.
 * All extensions being added in a tracker will automatically be removed when the extension is uninstalled from the registry.
 * Users interested in extension removal can register a handler that will let them know when an object is being removed.
 * <p>
 * This interface can be used without OSGi running.
 * </p><p>
 * This interface is not intended to be implemented by clients.
 * </p>
 * @since 3.1
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IExtensionTracker {

	/**
	 * Register an extension change handler with this tracker using the given filter.
	 * 
	 * @param handler the handler to be registered
	 * @param filter the filter to use to choose interesting changes
	 */
	function registerHandler(handler:IExtensionChangeHandler, filter:Function):void;

	/**
	 * Unregister the given extension change handler previously registered with this tracker.
	 * 
	 * @param handler the handler to be unregistered 
	 */
	function unregisterHandler(handler:IExtensionChangeHandler):void;

	/**
	 * Create an association between the given extension and the given object.
	 * The referenceType indicates how strongly the object is being kept in memory.
	 * There is 3 possible values: {@link #REF_STRONG}, {@link #REF_SOFT}, {@link #REF_WEAK}.
	 * 
	 * @param extension the extension 
	 * @param object the object to associate with the extension
	 * @param referenceType one of REF_STRONG, REF_SOFT, REF_WEAK
	 * @see #REF_STRONG
	 * @see #REF_SOFT
	 * @see #REF_WEAK
	 */
	function registerObject(extension:IExtension, object:Object, useWeakReference:Boolean = false):void;

	/**
	 * Remove an association between the given extension and the given object.
	 * 
	 * @param extension the extension under which the object has been registered
	 * @param object the object to unregister
	 */
	function unregisterObject(extension:IExtension, object:Object):void;

	/**
	 * Remove all the objects associated with the given extension. 
	 * 
	 * @param extension the extension for which the objects are removed
	 * @return the objects that were associated with the extension
	 */
	function unregisterObjects(extension:IExtension):void;

	/**
	 * Return all the objects that have been associated with the given extension.
	 * All objects registered strongly will be return unless they have been unregistered.
	 * The objects registered softly or weakly may not be returned if they have been garbage collected. 
	 * Return an empty array if no associations exist.
	 * 
	 * @param extension the extension for which the object must be returned 
	 * @return the array of associated objects
	 */
	function getObjects(extension:IExtension):Array;

	/**
	 * Close the tracker. All registered objects are freed and all handlers are being automatically removed.
	 */
	function close():void;
}
}